home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / rmaxtsk.exe / RMAXTASK.DOC < prev    next >
Text File  |  1991-12-30  |  57KB  |  1,152 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                    RMAXTask
  22.  
  23.                    A Multitasking Environment for C and C++
  24.  
  25.                                   Version 1.0
  26.  
  27.                                       ---
  28.  
  29.                               Copyright (c) 1991
  30.                             RMAX Development Group
  31.                          1033 East Coral Gables Drive
  32.                             Phoenix, Arizona 85022
  33.  
  34.                                                                Page 1
  35.  
  36.           TABLE OF CONTENTS
  37.           -----------------
  38.  
  39.           LEGAL INFORMATION . . . . . . . . . . . . . . . . . . .  2
  40.  
  41.           INTRODUCTION  . . . . . . . . . . . . . . . . . . . . .  3
  42.  
  43.              What is RMAXTask?  . . . . . . . . . . . . . . . . .  3
  44.              What is Multitasking?  . . . . . . . . . . . . . . .  3
  45.              Why Do I Need Multitasking?  . . . . . . . . . . . .  4
  46.  
  47.           RMAXTask TECHNICAL INFORMATION  . . . . . . . . . . . .  8
  48.  
  49.              How Does RMAXTask Work?  . . . . . . . . . . . . . .  8
  50.              RMAXTask Function Overviews  . . . . . . . . . . . .  9
  51.  
  52.           RMAXTask FUNCTION REFERENCE . . . . . . . . . . . . . . 12
  53.  
  54.              check_mail() . . . . . . . . . . . . . . . . . . . . 12
  55.              check_sem()  . . . . . . . . . . . . . . . . . . . . 12
  56.              create_mailbox() . . . . . . . . . . . . . . . . . . 12
  57.              create_sem() . . . . . . . . . . . . . . . . . . . . 12
  58.              create_task(). . . . . . . . . . . . . . . . . . . . 13
  59.  
  60.              fake_key() . . . . . . . . . . . . . . . . . . . . . 14
  61.              get_mail() . . . . . . . . . . . . . . . . . . . . . 14
  62.              get_status() . . . . . . . . . . . . . . . . . . . . 15
  63.              key_hit()  . . . . . . . . . . . . . . . . . . . . . 15
  64.              kill_task()  . . . . . . . . . . . . . . . . . . . . 15
  65.  
  66.              RMAX_time()  . . . . . . . . . . . . . . . . . . . . 16
  67.              send_mail()  . . . . . . . . . . . . . . . . . . . . 16
  68.              signal_sem() . . . . . . . . . . . . . . . . . . . . 16
  69.              start_RMAXTask() . . . . . . . . . . . . . . . . . . 17
  70.              stop_RMAXTask()  . . . . . . . . . . . . . . . . . . 17
  71.  
  72.              suspend()  . . . . . . . . . . . . . . . . . . . . . 17
  73.              wait_key() . . . . . . . . . . . . . . . . . . . . . 18
  74.              wait_sem() . . . . . . . . . . . . . . . . . . . . . 18
  75.              yield()  . . . . . . . . . . . . . . . . . . . . . . 19
  76.  
  77.           RMAXTask QUESTIONS AND ANSWERS  . . . . . . . . . . . . 20
  78.  
  79.           APPENDIX A - IBM PC EXTENDED KEYBOARD CODES . . . . . . 22
  80.  
  81.           APPENDIX B - RMAXTask REVISION HISTORY  . . . . . . . . 24
  82.  
  83.  
  84.                                                                Page 2
  85.  
  86.           LEGAL INFORMATION
  87.           -----------------
  88.  
  89.           This is the RMAXTask multitasking library for C.  This
  90.           library is copyrighted, but you may use and distribute the
  91.           shareware version of the library under the following
  92.           conditions:
  93.  
  94.           1.  By using the library, you agree that you do so at your
  95.               own risk, and to hold both RMAX Development Group and the
  96.               authors of these programs harmless from any liability for
  97.               loss or damage of any kind suffered by you arising from
  98.               your use of these programs.
  99.  
  100.           2.  You may freely copy and distribute the shareware files,
  101.               provided that you distribute them all together in their
  102.               original form, without any changes, additions or
  103.               deletions.  No fee may be charged for distributing the
  104.               files, except that you may charge not more than a $10.00
  105.               disk copying fee for each physical copy you distribute.
  106.  
  107.           3.  You may not create programs intended for sale using the
  108.               RMAXTask library unless you have registered your copy,
  109.               nor may you continue to use the shareware files for more
  110.               than 30 days after receiving them without registering.
  111.               Upon registration, you will receive the full source code
  112.               to the library, pre-compiled libraries for all the memory
  113.               models for both C and C++, and a license allowing
  114.               unrestricted use of the library routines in your own
  115.               programs.
  116.  
  117.           To register your copy of RMAXTask, simply fill out the form
  118.           found in the file REGISTER.TXT and return it along with your
  119.           registration fee.
  120.  
  121.  
  122.                                                                Page 3
  123.  
  124.           WHAT IS RMAXTask?
  125.           -----------------
  126.  
  127.           RMAXTask is a library of C functions that lets you run one or
  128.           more C functions together in a priority-based, cooperative
  129.           (non-preemptive) multitasking environment.  RMAXTask
  130.           provides full support for intertask synchronization and
  131.           communication, timed delays, and access to the PC's keyboard.
  132.  
  133.           RMAXTask provides a more capable scheduler and better
  134.           intertask communication than do simple round-robin task
  135.           switchers such as Wayne Conrad's MTASK or the system
  136.           described in the October, 1988 issue of "Computer Language"
  137.           magazine, while avoiding the complexity of a full-blown
  138.           interrupt-driven, preepmtive system like Thomas Wagner's
  139.           CTask.
  140.  
  141.  
  142.           WHAT IS MULTITASKING?
  143.           ---------------------
  144.  
  145.           Multitasking is a way to divide a single program into several
  146.           distinct threads of execution called "tasks" which execute
  147.           concurrently under the control of a supervisory program
  148.           called a "scheduler".  The tasks are usually somewhat
  149.           independent of one another (although they can communicate
  150.           among themselves) and appear to execute all at once.  On a
  151.           single-CPU system, of course, only one task can be running at
  152.           any given instant, but the scheduler passes control to the
  153.           various tasks in a way that gives the illusion that they are
  154.           all running at the same time.
  155.  
  156.           Multitasking as implemented by RMAXTask is not to be confused
  157.           with multiprogramming (as provided by Windows or an operating
  158.           system like QNX), in which multiple -programs- appear to run
  159.           at the same time, or with multiprocessing, which requires a
  160.           computer with more than one CPU.  When you use RMAXTask, you
  161.           compile and link all your tasks together into a single
  162.           program which appears (and is) to the operating system just
  163.           like any other program.
  164.  
  165.  
  166.           PREEMPTIVE VS. COOPERATIVE MULTITASKING
  167.           ---------------------------------------
  168.  
  169.           In a "preemptive" multitasking system, the scheduler doles
  170.           out CPU time to the tasks in chunks called "time slices".
  171.           Each task is allowed to execute for a specific time period,
  172.           after which control is wrested from it by the timer interrupt
  173.           and given to some other task by the scheduler.  The advantage
  174.           of such a scheme is that tasks can be written with little or
  175.           no awareness of the multitasking system.  The downside,
  176.           however, is that it can be difficult to make sure that tasks
  177.                                                                Page 4
  178.  
  179.           are not interrupted at inappropriate times.  As an example,
  180.           consider a task which has just made a DOS call to write to a
  181.           file.  If it is interrupted while it is within DOS and
  182.           control is then passed to a different task which also calls
  183.           DOS, havoc will reign shortly because DOS is not re-entrant.
  184.  
  185.           In a "cooperative" multitasking environment, a task once
  186.           running continues to run until it explicitly relinquishes
  187.           control by making a call to the multitasking system.  As a
  188.           result, such tasks must be wr